@ampless/runtime 0.2.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ampless contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,83 @@
+# @ampless/runtime
+
+Public-side runtime for [ampless](https://github.com/heavymoons/ampless). Bundles the post-fetching client, site settings, theme resolution, SEO metadata aggregation, middleware, and public route handlers behind a single `createAmpless()` factory.
+
+> **Pre-release / alpha.** Breaking changes possible in any minor version until v1.0.
+
+Splitting this out of the template lets you `npm update @ampless/runtime` without touching scaffolded files — public-site behaviour upgrades come in through the package, not by re-running the scaffolder.
+
+## Install
+
+```bash
+npm install @ampless/runtime@alpha ampless@alpha
+```
+
+`@ampless/runtime` declares peer dependencies on `next` (15+), `react` (18/19), `aws-amplify` (6+), and `@aws-amplify/adapter-nextjs` (1+). The CLI scaffolder pins compatible versions in the template's `package.json`.
+
+## Usage
+
+Templates create one shared instance at `lib/ampless.ts`:
+
+```ts
+import outputs from '../amplify_outputs.json'
+import cmsConfig from '../cms.config'
+import { themes, DEFAULT_THEME } from '../themes-registry'
+import { createAmpless } from '@ampless/runtime'
+
+export const ampless = createAmpless({
+  outputs,
+  cmsConfig,
+  themes: { themes, defaultTheme: DEFAULT_THEME },
+})
+```
+
+Routes and dispatchers under `app/site/[siteId]/` become one-line factory invocations:
+
+```ts
+// app/site/[siteId]/page.tsx
+import { ampless } from '@/lib/ampless'
+import {
+  createThemeHomeDispatcher,
+  createThemeHomeMetadata,
+} from '@ampless/runtime/dispatchers'
+
+export const dynamic = 'force-dynamic'
+export const generateMetadata = createThemeHomeMetadata(ampless)
+export default createThemeHomeDispatcher(ampless)
+```
+
+```ts
+// app/site/[siteId]/og/[slug]/route.ts
+import { ampless } from '@/lib/ampless'
+import { createOgRouteHandler } from '@ampless/runtime/routes'
+
+export const runtime = 'nodejs'
+export const dynamic = 'force-dynamic'
+export const GET = createOgRouteHandler(ampless)
+```
+
+Middleware:
+
+```ts
+// middleware.ts
+import cmsConfig from './cms.config'
+import { createAmplessMiddleware, defaultMatcherConfig } from '@ampless/runtime/middleware'
+
+export const middleware = createAmplessMiddleware({ cmsConfig })
+export const config = defaultMatcherConfig
+```
+
+## Sub-paths
+
+- `@ampless/runtime` — `createAmpless`, runtime types, and re-exports of `renderBody`, `renderThemeCss`, format converters
+- `@ampless/runtime/middleware` — `createAmplessMiddleware`, `defaultMatcherConfig`
+- `@ampless/runtime/routes` — `createOgRouteHandler`, `createSitemapRouteHandler`, `createFeedRouteHandler`, `createRawRouteHandler`
+- `@ampless/runtime/dispatchers` — `createThemeHomeDispatcher`, `createThemePostDispatcher`, `createThemeTagDispatcher` (each with a matching `*Metadata` factory)
+
+## What's still in the template
+
+Admin-side modules (post providers, theme actions, auth, kv writes) and theme components stay in the scaffold. They move into `@ampless/admin` in a later release; until then, edits to those files belong in the user's project.
+
+## License
+
+MIT

package/dist/dispatchers/index.d.ts

@@ -0,0 +1,59 @@
+import { Metadata } from 'next';
+import { Ampless } from '../index.js';
+import 'ampless';
+
+interface Props$2 {
+    params: Promise<{
+        siteId: string;
+    }>;
+}
+type ThemeHomeDispatcher = (props: Props$2) => Promise<unknown>;
+type ThemeHomeMetadata = (props: Props$2) => Promise<Metadata>;
+/**
+ * Home page dispatcher. Resolves the active theme for the request's
+ * siteId and renders the theme's `components.Home` server component
+ * with the same `params` Promise it was passed.
+ *
+ * The return type is `unknown` (cast at the route boundary) because
+ * Next.js page-component prop types vary by route shape and the
+ * underlying theme components are arbitrary server components.
+ */
+declare function createThemeHomeDispatcher(ampless: Ampless): ThemeHomeDispatcher;
+/** generateMetadata factory for the home dispatcher. */
+declare function createThemeHomeMetadata(ampless: Ampless): ThemeHomeMetadata;
+
+interface Props$1 {
+    params: Promise<{
+        siteId: string;
+        slug: string;
+    }>;
+}
+type ThemePostDispatcher = (props: Props$1) => Promise<unknown>;
+type ThemePostMetadata = (props: Props$1) => Promise<Metadata>;
+/**
+ * Post page dispatcher. Resolves the active theme and renders the
+ * theme's `components.Post` server component. If the theme doesn't
+ * declare a Post component, returns Next.js's notFound() (404).
+ */
+declare function createThemePostDispatcher(ampless: Ampless): ThemePostDispatcher;
+/** generateMetadata factory for the post dispatcher. */
+declare function createThemePostMetadata(ampless: Ampless): ThemePostMetadata;
+
+interface Props {
+    params: Promise<{
+        siteId: string;
+        tag: string;
+    }>;
+}
+type ThemeTagDispatcher = (props: Props) => Promise<unknown>;
+type ThemeTagMetadata = (props: Props) => Promise<Metadata>;
+/**
+ * Tag page dispatcher. Resolves the active theme and renders the
+ * theme's `components.Tag` server component. If the theme doesn't
+ * declare a Tag component, returns Next.js's notFound() (404).
+ */
+declare function createThemeTagDispatcher(ampless: Ampless): ThemeTagDispatcher;
+/** generateMetadata factory for the tag dispatcher. */
+declare function createThemeTagMetadata(ampless: Ampless): ThemeTagMetadata;
+
+export { type ThemeHomeDispatcher, type ThemeHomeMetadata, type ThemePostDispatcher, type ThemePostMetadata, type ThemeTagDispatcher, type ThemeTagMetadata, createThemeHomeDispatcher, createThemeHomeMetadata, createThemePostDispatcher, createThemePostMetadata, createThemeTagDispatcher, createThemeTagMetadata };

package/dist/dispatchers/index.js

@@ -0,0 +1,65 @@
+// src/dispatchers/home.ts
+function createThemeHomeDispatcher(ampless) {
+  return async function SiteHomeDispatcher({ params }) {
+    const { siteId } = await params;
+    const { module } = await ampless.resolveActiveTheme(siteId);
+    const Home = module.components.Home;
+    return await Home({ params });
+  };
+}
+function createThemeHomeMetadata(ampless) {
+  return async function generateMetadata({ params }) {
+    const { siteId } = await params;
+    const { module } = await ampless.resolveActiveTheme(siteId);
+    const fn = module.metadata?.Home;
+    return fn ? await fn({ params }) : {};
+  };
+}
+
+// src/dispatchers/post.ts
+import { notFound } from "next/navigation";
+function createThemePostDispatcher(ampless) {
+  return async function SitePostDispatcher({ params }) {
+    const { siteId } = await params;
+    const { module } = await ampless.resolveActiveTheme(siteId);
+    const Post = module.components.Post;
+    if (!Post) notFound();
+    return await Post({ params });
+  };
+}
+function createThemePostMetadata(ampless) {
+  return async function generateMetadata({ params }) {
+    const { siteId } = await params;
+    const { module } = await ampless.resolveActiveTheme(siteId);
+    const fn = module.metadata?.Post;
+    return fn ? await fn({ params }) : {};
+  };
+}
+
+// src/dispatchers/tag.ts
+import { notFound as notFound2 } from "next/navigation";
+function createThemeTagDispatcher(ampless) {
+  return async function SiteTagDispatcher({ params }) {
+    const { siteId } = await params;
+    const { module } = await ampless.resolveActiveTheme(siteId);
+    const Tag = module.components.Tag;
+    if (!Tag) notFound2();
+    return await Tag({ params });
+  };
+}
+function createThemeTagMetadata(ampless) {
+  return async function generateMetadata({ params }) {
+    const { siteId } = await params;
+    const { module } = await ampless.resolveActiveTheme(siteId);
+    const fn = module.metadata?.Tag;
+    return fn ? await fn({ params }) : {};
+  };
+}
+export {
+  createThemeHomeDispatcher,
+  createThemeHomeMetadata,
+  createThemePostDispatcher,
+  createThemePostMetadata,
+  createThemeTagDispatcher,
+  createThemeTagMetadata
+};

package/dist/index.d.ts

@@ -0,0 +1,206 @@
+import { Post, ThemeModule, ThemeManifest, Config } from 'ampless';
+export { Config, Post, ThemeManifest } from 'ampless';
+import { Metadata } from 'next';
+
+interface StorageOutput {
+    bucket_name: string;
+    aws_region: string;
+}
+interface DataOutput {
+    url: string;
+    aws_region: string;
+    default_authorization_type?: string;
+    api_key?: string;
+}
+interface AmplessOutputs {
+    storage?: StorageOutput;
+    data?: DataOutput;
+    [key: string]: unknown;
+}
+
+interface StorageApi {
+    publicAssetUrl(key: string): string;
+    isStorageConfigured(): boolean;
+}
+
+interface PublicPostShape {
+    postId: string;
+    siteId: string;
+    slug: string;
+    title: string;
+    excerpt?: string | null;
+    format?: string | null;
+    body?: unknown;
+    status?: string | null;
+    publishedAt?: string | null;
+    tags?: Array<string | null> | null;
+}
+interface PublicPostConnectionShape {
+    items?: Array<PublicPostShape | null> | null;
+    nextToken?: string | null;
+}
+interface ListPostsOptions {
+    siteId?: string;
+    /** ISO 8601 timestamp; SK lower bound (inclusive). */
+    from?: string;
+    /** ISO 8601 timestamp; SK upper bound (inclusive). */
+    to?: string;
+    limit?: number;
+    /** Opaque cursor returned by a previous call. */
+    nextToken?: string;
+}
+interface ListPostsByTagOptions {
+    siteId?: string;
+    limit?: number;
+    nextToken?: string;
+}
+interface ListPostsResult {
+    items: Post[];
+    nextToken: string | null;
+}
+interface PostsApi {
+    listPublishedPosts(opts?: ListPostsOptions): Promise<ListPostsResult>;
+    getPublishedPost(slug: string, opts?: {
+        siteId?: string;
+    }): Promise<Post | null>;
+    listPostsByTag(tag: string, opts?: ListPostsByTagOptions): Promise<ListPostsResult>;
+}
+
+interface EffectiveSiteSettings {
+    site: {
+        name: string;
+        url: string;
+        description?: string;
+    };
+    media: {
+        imageDisplay?: 'inline' | 'lightbox';
+        imageMaxWidth?: string;
+        processing?: {
+            maxDimension?: number;
+            format?: 'webp' | 'jpeg' | 'original';
+            quality?: number;
+            losslessForPng?: boolean;
+        };
+    };
+    dateFormat?: 'iso' | 'long' | 'locale';
+    timezone?: string;
+}
+interface SiteSettingsApi {
+    loadSiteSettings(siteId?: string): Promise<EffectiveSiteSettings>;
+}
+
+interface SeoApi {
+    postMetadata(post: Post, siteId?: string): Promise<Metadata>;
+    siteMetadata(siteId?: string): Promise<Metadata>;
+}
+
+interface ThemesRegistry {
+    /** Map of theme name → loaded theme module. */
+    themes: Record<string, ThemeModule>;
+    /** Name used when no `theme.active` override is stored for the site. */
+    defaultTheme: string;
+}
+interface ResolvedTheme {
+    name: string;
+    module: ThemeModule;
+}
+interface ThemeActiveApi {
+    resolveActiveTheme(siteId?: string): Promise<ResolvedTheme>;
+}
+
+interface EffectiveThemeConfig {
+    /** Resolved active theme name (e.g. 'blog'). */
+    activeTheme: string;
+    manifest: ThemeManifest;
+    /** Resolved values, keyed by manifest field key. Always populated. */
+    values: Record<string, string>;
+    /** Subset of `values` for fields that have a `cssVar`. */
+    cssVars: Record<string, string>;
+}
+interface ThemeConfigApi {
+    loadThemeConfig(siteId?: string): Promise<EffectiveThemeConfig>;
+}
+/**
+ * Render `cssVars` as the body of a `:root { ... }` CSS block. Values
+ * have already been validated by `resolveThemeValues`, so the output is
+ * safe to inline via `dangerouslySetInnerHTML`.
+ */
+declare function renderThemeCss(cssVars: Record<string, string>): string;
+
+declare function renderBody(post: Post): string;
+/**
+ * Convert a tiptap doc to its HTML form. Same renderer the public
+ * site uses. Defensive: tiptap accepts an HTML string as initial
+ * content and parses it on mount, but won't fire onUpdate until the
+ * user edits — so a format-switch chain (e.g. markdown → tiptap →
+ * markdown without editing) can still hand us a raw HTML string
+ * here. In that case, return it as-is rather than walking it as a
+ * malformed tiptap node and producing empty output.
+ */
+declare function tiptapToHtml(doc: unknown): string;
+/** Convert markdown to HTML using the built-in minimal renderer. */
+declare function markdownToHtml(md: string): string;
+/**
+ * Walk a tiptap doc and emit Markdown. Mirrors `renderTiptap` in
+ * shape but produces markdown syntax. Loses anything markdown can't
+ * express (data attributes, image display modes, custom marks).
+ *
+ * Same defensive path as tiptapToHtml: a string input means tiptap
+ * hasn't emitted JSON yet (the body is still the HTML we handed it).
+ * Route through htmlToMarkdown so the content survives.
+ */
+declare function tiptapToMarkdown(doc: unknown): string;
+/**
+ * Regex-based HTML → Markdown converter. Handles the tag set the
+ * editor produces (`<p>` `<h1>`-`<h6>` `<strong>` `<em>` `<a>`
+ * `<img>` `<ul>` `<ol>` `<li>` `<code>` `<pre>` `<blockquote>` `<hr>`
+ * `<br>`). Anything else (tables, sections, divs) keeps its content
+ * but loses structural meaning.
+ *
+ * Not a full library — there are known limits like nested formatting
+ * inside list items potentially merging. Acceptable for a v0.x
+ * format-switch convenience; complex HTML round-trips shouldn't be
+ * relied on.
+ */
+declare function htmlToMarkdown(html: string): string;
+
+interface CreateAmplessOpts {
+    outputs: AmplessOutputs;
+    cmsConfig: Config;
+    themes: ThemesRegistry;
+}
+interface Ampless {
+    listPublishedPosts(opts?: ListPostsOptions): Promise<ListPostsResult>;
+    getPublishedPost(slug: string, opts?: {
+        siteId?: string;
+    }): Promise<Post | null>;
+    listPostsByTag(tag: string, opts?: ListPostsByTagOptions): Promise<ListPostsResult>;
+    loadSiteSettings(siteId?: string): Promise<EffectiveSiteSettings>;
+    resolveActiveTheme(siteId?: string): Promise<ResolvedTheme>;
+    loadThemeConfig(siteId?: string): Promise<EffectiveThemeConfig>;
+    postMetadata(post: Post, siteId?: string): Promise<Metadata>;
+    siteMetadata(siteId?: string): Promise<Metadata>;
+    renderBody(post: Post): string;
+    renderThemeCss(cssVars: Record<string, string>): string;
+    publicAssetUrl(key: string): string;
+    isStorageConfigured(): boolean;
+    readonly outputs: AmplessOutputs;
+    readonly cmsConfig: Config;
+    readonly themes: ThemesRegistry;
+    readonly posts: PostsApi;
+    readonly settings: SiteSettingsApi;
+    readonly seo: SeoApi;
+    readonly themeActive: ThemeActiveApi;
+    readonly themeConfig: ThemeConfigApi;
+    readonly storageApi: StorageApi;
+}
+/**
+ * Wire up the ampless runtime from user-supplied config blobs. The
+ * returned `Ampless` instance is the single object handed to route
+ * dispatchers / metadata factories / middleware — each sub-API
+ * (posts, settings, themes, ...) is also available individually on
+ * the instance for cases where a thin handler only needs one piece.
+ */
+declare function createAmpless(opts: CreateAmplessOpts): Ampless;
+
+export { type Ampless, type AmplessOutputs, type CreateAmplessOpts, type DataOutput, type EffectiveSiteSettings, type EffectiveThemeConfig, type ListPostsByTagOptions, type ListPostsOptions, type ListPostsResult, type PostsApi, type PublicPostConnectionShape, type PublicPostShape, type ResolvedTheme, type SeoApi, type SiteSettingsApi, type StorageOutput, type ThemeActiveApi, type ThemeConfigApi, type ThemesRegistry, createAmpless, htmlToMarkdown, markdownToHtml, renderBody, renderThemeCss, tiptapToHtml, tiptapToMarkdown };